COMMENT ⊗   VALID 00003 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	The MAIL program.				July 6, 1973
C00019 00003	The REMIND command.
C00029 ENDMK
C⊗;
The MAIL program.				July 6, 1973

This document describes the use of the MAIL and SEND monitor
commands, which are used to send messages to users.  The
SEND command sends the message to the user's console, if
he is logged in, and optionally may also (or instead, if
he isn't logged in) send it to him as MAIL, so it will
be seen on login.  The second section describes the REMIND
command, for automatic delayed messages, and the LATER
command, for automatic delayed program execution.

The basic format of the MAIL command is

	.MAIL <switches> <destination list> <message>

and that of the SEND command is

	.SEND <switches> <destination list> <message>

Another command, for complaining about system bugs, has the format

	.GRIPE <message>

This is a version of MAIL which is directed to a special system area.

The only switches allowed with the MAIL command are /D and /U.
The /D switch causes a list of the destinations specified by the
command to be added to the message as its last line, preceded by
"CC: ".  If a distribution list file is used, both the file spec
and the contents are included.  Note: all specified destinations
are listed, even if invalid.

The /U switch is used if for some reason you need to send a message
to a user who is not known to the system (has no UFD).  It allows
this but gives a warning message and asks you for each unknown
addressee whether you really mean it.  These switches may also be
used with SEND and REMIND, in addition to the ones listed below.

There are three mutually exclusive switches which may optionally
be used with the SEND command.  All have to do with the option of
mailing messages. Normally, SEND will just send messages to
consoles of logged-in users (at all consoles where logged in), but if
a destination of the form PRG (see the next paragraph) is not
logged in anywhere, the user will be given the option of mailing
the message to that prg instead.  The switches /Y for Yes or
/N for No will assume that response whenever the situation
arises.  The switch /M for Mail will always mail to all
destinations on the list as well as sending to their consoles
even if they are logged in.

Another switch used only with SEND is /W, for "where", which lists
on the user's console the ppn, job number, job name, queue, and
console number of all (logged in) recipients of the message.

The destination list for MAIL can be just * , which will send the
message to the file NOTICE.TXT[2,2] so all users will see it on login.
Otherwise, it is one or more project and/or programmer names
separated by commas.  The elements of the list should be in
the form PRG or [PRJ,*] or [PRJ,PRG] .  Any PRJ or PRG can be
a dot (.) to mean the same as the user's prj or prg name (real
ppn, not alias).  List elements may also take the form
@<file specification> (default device DSK, default extension
DIS as in DIStribution list); the specified file will be read
and will replace the @ field in the command.  If such a file
contains an @ field, the newly specified file will be read and
the remainder of the old file, if any, will be ignored.  The DIS
file may have a TV/E directory and/or SOS line numbers, which will
be ignored.  (Note: if the file specification does not give an
explicit extension, the given file name with no extension will be
tried before the default extension given above.)  The DIS file
may have any number of lines; destinations are separated by any
combination of crlfs, spaces, and zero or one comma.  Lines in the
DIS file may contain comments started by semicolons, which will be
ignored; note that this is not true of the command line typed at
the console!  In the @ file specification, the notation [PRJ] may
be used to mean [PRJ,.].  The notation ↓chars↓ may be used to
include non-alphamerics in a file name.  To make it easier to refer
to mail files as messages (see below), the filename scanner will
also accept "filenames" of the form ∂ or ∂PRG or ∂PRJ,PRG or
∂PRJ, or ∂PRJ,*.  The first case uses your own logged in
programmer name, as does the ∂PRJ, form.  These imply device DSK,
and default extension MSG and ppn [2,2], although extension or
ppn can be specified explicitly.

For the SEND command, there are two special forms of destinations:
a job number, and a device name followed by a colon.  These special
forms can only be used alone, i.e., with no other destinations.
The form SEND * will send the message to all logged-in users.

The message part of the command may be a one-line message, which
will be sent as is; or an @file specification (default extension
TXT); or null, in which case the program will request a multi-line
message from the user.  Any TV/E directory, SOS line numbers, and
form feeds in a message file will be ignored.  If you start typing
a short message on the command line, and decide you need more than
one line after all, you can end the command line with <lf> instead
of <cr> and you will be allowed to continue the message.

Messages can only be sent to real consoles, or to pseudo-ttys
which are connected to the IMP (ARPA users).  This excludes
detached jobs and non-ARPA PTYs.  SEND * sends only to those
consoles at which someone is logged in.

Mail can only be sent to defined users, i.e., there must be a
UFD matching the destination prj and/or prg names (unless the
/U switch is used, as explained above, to permit it).  The mail
is put in the front of the file <ppn>.MSG[2,2].  If the mail
is sent to all users via MAIL *, the program also scans the old
NOTICE.TXT[2,2] file as it copies it, and deletes any messages
more than two weeks old.  Also, TV directories and SOS line
numbers are deleted from the old messages in this case.

The check for a file directory for the specified user(s) is made
before the program asks for the message if the multi-line option
is used.  If there are no valid destinations, the program exits
without doing anything else.  If any destinations are valid,
however, the program continues as if only the valid destinations
were specified.  (Exception: the list provided by /D includes
all specified destinations, valid or invalid.)  Note: in the case
of SEND, the only check made before the message is typed in is
the file directory check.  The check for the user(s) being logged
in is not made until later.

There is actually a way not-logged-in users can get messages sent
by SEND: it is possible to declare a particular console to be your
"home" console for SEND purposes.  If you have a file called
OPTION.TXT[1,prg] which includes a line of the form SEND:number
then if someone sends you a message with SEND and you are not logged
in, a message will be typed on the tty specified by the above number
indicating that the message is coming, and it will be mailed as if
the sender had said SEND/Y.  You can read the message by saying RCV prg.
You need not be logged in to do this, but if you are it destroys your core
image.  Oh, yeah, if the message is sent to [prj,prg] rather than prg, it
looks for OPTION.TXT in [prj,prg] rather than [1,prg].


When a message is MAILed by the MAIL command (not SEND/M, etc.)
to a user who is logged in, a one-line notice is sent to his
console indicating that mail has arrived.  This also applies to
mail-only reminders (see REMIND/M, next section).

A sample command is
MAIL BH,@FOONLY,[S,*] TEXT OF MESSAGE
which will send the message "TEXT OF MESSAGE" to ↓    BH↓.MSG[2,2],
↓  S↓.MSG[2,2], and whatever users are listed in FOONLY.DIS in
the user's disk area.

Spaces may be used in all reasonable places in the command.  For
the benefit of any weird people who want to start messages with
a comma, there is another syntax in which the destination list
is enclosed in parentheses.  In this case spaces may separate
destinations instead of commas if you want.  This syntax is also
handy for SENDing to a numeric programmer name (otherwise it
would be considered a job number) and similarly useless things.

There is an error recovery feature for people who type in long
messages, only to discover that because of a typing error they are
trying to send it to a non-existent destination or something; to wit:
If, at the end of a multi-line message, you type <ctrl><meta><altmode>
instead of <ctrl><meta><linefeed>, the message will not be transmitted.
Instead, the original command will be loaded into your line editor,
and you can correct and re-enter it, but if it does not include a
message, the old message will be used instead of asking for a new one.
Also, the same effect can be gotten by giving a monitor REENTER
command after the program exits or you <call> out of it.  From a
non-display teletype, of course, the line editor feature is not
available, but you can still REENTER and retype the command line.
Note: this reenter facility only works after the message has been
completely entered; do not <call> in the middle of typing the
message and reenter, use <ctrl><meta><altmode> instead.

The mail program can be invoked by other programs in two ways.
First, there is the usual RPG system: if SYS:MAIL.DMP is started
at one location after its usual start address, it will try to read
a file DSK:QQMAI.RPG which should contain the command.  This file
may not contain line numbers or a directory, just the command.
The command is scanned up to a linefeed or zero byte, except that
only the first 32. words of the file are examined, so long messages
must be entered with the @ feature.  If no RPG file is found, MAIL
will request a command from the teletype.  Another procedure is
also allowed, to make it easier to send messages without having to
write a file: if MAIL is started two locations after its start address,
it does a WRCV and will accept a command in its mailbox.  Programs
written to use this feature should wait between the SWAP and the SEND
UUOs in order to make sure the program was really loaded, otherwise
the mail will be lost.  Some other considerations: obviously, if
the MAIL job does not have a teletype, the long message input mode
cannot be used; if the command has neither the message text nor a
message file specification, nothing is done.  Also, in this case,
SEND with no switches is equivalent to SEND/Y.
The REMIND command.
--- ------ --------

The REMIND command is used to tell the MAIL program to send and mail
your message at a specified later date and time, possibly repeatedly.
The basic syntax is

	.REMIND <switches> <destination list> <datime> <count> <message>

The allowable switches are /S for send only or /M for mail only.  If
neither is used, the message is both sent and mailed.  /D and /U may
also be used, as in MAIL or SEND.

The destination list and message fields function like those of the
MAIL command, as described in the previous section.  Reminder
recipients must be users known to the system, i.e., they must have
a UFD (unless you use the /U switch as explained on the previous
page).  The destination field may be omitted, in which case your
own programmer name will be used as if the destination field were
the character "."; NOTE, however, that some forms of datime (those
which start with a letter) could be confused with destinations, and
if you want to use such a form there must be an explicit destination.

The datime field may specify a date, a time, or both.  The formats
allowed for dates are illustrated here:

	4/28/75		28-APR-75	APR 28, 75
	4/28/1975	28-APR-1975	APR 28, 1975
	4/28		28-APR		APR 28
	4/28/*		28-APR-*	APR 28, *
	*/28		28-*		+3
	WED		WED*		W		W*

The forms without a year imply this year unless the date is today or
earlier, in which case next year is used.  Letters may be upper or
lower case; all after the first three are ignored.  The days of the
week have, for convenience, the single-letter names familiar to
Farmers' Almanac readers and former MIT students: M,T,W,R,F,S,D.
Asterisk as a month or year is wildcard; note that forms like */28
expire at the end of the current year.  WED* and W* mean every Wednesday.
The +3 form is the number of days later than today, i.e., three days
from now.  Spaces may generally be used or omitted as desired except
within a word or number, except for the APR 28 forms.  Certain mixed
notations such as "4/28, 1973" may work, or they may not.  If only a
time field is used without a date, today is assumed unless the time
is already past, in which case tomorrow is used.  The weekday forms
always imply a day between one and seven days from now as their first
or only instance, never today.  Here are the formats for times:

	1423		223pm		223p
	14:23		2:23pm		2:23p
	0223		223am		223a		223
	02:23		2:23am		2:23a		2:23
	2		2am		2pm		2a
	+2:23		+2:		+:23		2p

A date without a time means midnight.  The relative forms may only
be used without a date.  Letters may be upper or lower case.  There
may be spaces on either side of a colon, but NOT between the time
and the "am" or "pm"!  To use both a date and a time, they must be
enclosed in parentheses and separated by spaces: "(WED 3am)".

The optional count field is used to specify the number of instances
of a repeated request.  The format is #<number>.  If none is used,
#50 is assumed (the number is decimal).  The form #∞ may be used for
requests which are to live forever, but please don't leave these
around after you go away....

Here are sample commands:
	REMIND . (WED* 2:45P) #30 Go to 3:00 class!!
	Remind me, sir, to monitor your computer usage.
	REMIND * APR 15,* LAST DAY TO FILE INCOME TAX RETURNS

The messages will be both sent and mailed at the target time,
unless /S or /M is used to specify send-only or mail-only.  The
message header will say "(reminder)" to distinguish it from an
ordinary message.  All the features of MAIL work here, like @ fields
for destinations or messages, REENTER, etc.  There are the usual
syntactic ambiguities which are not expected to affect anyone in
practice: if the first nonblank after the command name is a digit,
it is taken as part of the datime field in REMIND, as opposed to
a programmer name in MAIL or a job number in SEND.

The LATER command is used to cause delayed exection of an arbitrary
program.  The format is:

	.LATER <filespec> <core> <datime> <count>

in which datime and count are as in the REMIND command.  The filespec
determines the program to be run; the default device is DSK (the only
other device allowed is SYS), and the default extension is DMP.  Note:
if no ppn is specified, the ppn used is your disk ppn (alias) at the
time the command is entered!  The delayed job is given your logged-in
ppn as its logged-in ppn regardless of the ppn of the dump file.  It
is run with JLOG off, i.e., it is killed if any error condition arises.
The optional core argument, if used, is enclosed in angle brackets.
It may include an initial core allocation and/or a starting address
offset, in the form "<3K,+1>".  The subarguments may be in either
order, and must be separated by a comma if both are used.  The core
allocation argument is in decimal units of 1024 words, and the
starting address offset is in octal words.  If no job slots are
available at the time the job is to be run, it is not done; therefore,
if you are depending on the result you should schedule the job for
non-prime time. (If there is no job slot for the REMIND phantom
itself, it will try to schedule your job as soon after the given time
as it is itself run, but it will only try once.)

The monitor command CANCEL will run a program which will list and
selectively delete reminder requests from or to you, or all requests
if you are logged in as [RMD,SYS].  This program can also be used to
list requests without asking whether you want to delete them: after
the first request is listed, type the letter L in answer to the
deletion question and any remaining requests will be listed without
interruption.  LATER requests are also listed and deleted by CANCEL.

Complaints regarding this program should be addressed to:
	Wastebasket
	Room 50-030
	Copernicus, The Moon  99973